
package org.apache.mina.common;

import java.util.List;
import org.apache.mina.common.IoFilter.NextFilter;
import org.apache.mina.common.IoFilter.WriteRequest;

/**
 * A container of {@link IoFilter}s that forwards {@link IoHandler} events to
 * the consisting filters and terminal {@link IoHandler} sequentially. Every
 * {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship).
 * 
 * IoFilter的容器，转发IoHandler事件到包含的过滤器，从而到达IoHandler终端。
 * 所有的IoSession都有自己的IoFilterChain（1对1关系）。
 */
public interface IoFilterChain {
    /**
     * Returns the parent {@link IoSession} of this chain.
     * 
     * 返回拥有此过滤链的IoSession。
     * 
     * @return {@link IoSession}
     */
    IoSession getSession();

    /**
     * Returns the {@link Entry} with the specified <tt>name</tt> in this chain.
     * 
     * 根据给定的name返回此链中包含的Entry。
     * 
     * @return <tt>null</tt> if there's no such name in this chain
     */
    Entry getEntry(String name);

    /**
     * Returns the {@link IoFilter} with the specified <tt>name</tt> in this
     * chain.
     * 
     * 根据给定的name返回此链中包含的IoFilter。
     * 
     * @return <tt>null</tt> if there's no such name in this chain
     */
    IoFilter get(String name);

    /**
     * Returns the {@link NextFilter} of the {@link IoFilter} with the specified
     * <tt>name</tt> in this chain.
     * 
     * 根据给定的name返回此参数对应的IoFilter的NextFilter。
     * 
     * @return <tt>null</tt> if there's no such name in this chain
     */
    NextFilter getNextFilter(String name);

    /**
     * Returns the list of all {@link Entry}s this chain contains.
     * 
     * 返回此链中包含的Entry列表。
     */
    List<Entry> getAll();

    /**
     * Returns the reversed list of all {@link Entry}s this chain contains.
     * 
     * 返回此链中包含的Entry反序列表。
     */
    List<Entry> getAllReversed();

    /**
     * Returns <tt>true</tt> if this chain contains an {@link IoFilter} with the
     * specified <tt>name</tt>.
     * 
     * 此链是否包含给定的name所对应的IoFilter。
     */
    boolean contains(String name);

    /**
     * Returns <tt>true</tt> if this chain contains the specified
     * <tt>filter</tt>.
     * 
     * 判断是否链是否包含此过滤器。
     */
    boolean contains(IoFilter filter);

    /**
     * Returns <tt>true</tt> if this chain contains an {@link IoFilter} of the
     * specified <tt>filterType</tt>.
     * 
     * 判断此链中是否包含为filterType类型的IoFilter。
     */
    boolean contains(Class<? extends IoFilter> filterType);

    /**
     * Adds the specified filter with the specified name at the beginning of
     * this chain.
     * 
     * 在链表首添加一个filter。
     * 
     * @throws IoFilterLifeCycleException
     *             if
     *             {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)}
     *             or {@link IoFilter#init()} throws an exception.
     * 
     */
    void addFirst(String name, IoFilter filter);

    /**
     * Adds the specified filter with the specified name at the end of this
     * chain.
     * 
     * 在链尾添加一个filter。
     * 
     * @throws IoFilterLifeCycleException
     *             if
     *             {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)}
     *             or {@link IoFilter#init()} throws an exception.
     */
    void addLast(String name, IoFilter filter);

    /**
     * Adds the specified filter with the specified name just before the filter
     * whose name is <code>baseName</code> in this chain.
     * 
     * 将指定的filter添加到baseName对应的IoFilter之前。
     * 
     * @throws IoFilterLifeCycleException
     *             if
     *             {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)}
     *             or {@link IoFilter#init()} throws an exception.
     */
    void addBefore(String baseName, String name, IoFilter filter);

    /**
     * Adds the specified filter with the specified name just after the filter
     * whose name is <code>baseName</code> in this chain.
     * 
     * 将指定的filter添加到baseName对应的IoFilter之后。
     * 
     * @throws IoFilterLifeCycleException
     *             if
     *             {@link IoFilter#onPostAdd(IoFilterChain, String, NextFilter)}
     *             or {@link IoFilter#init()} throws an exception.
     * 
     */
    void addAfter(String baseName, String name, IoFilter filter);

    /**
     * Removes the filter with the specified name from this chain.
     * 
     * 从链中移除给定name所对应的filter。
     * 
     * @throws IoFilterLifeCycleException
     *             if
     *             {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)}
     *             or {@link IoFilter#destroy()} throws an exception.
     */
    IoFilter remove(String name);

    /**
     * Removes all filters added to this chain.
     * 
     * 从链中移除所有的过滤器。
     * 
     * @throws Exception
     *             if
     *             {@link IoFilter#onPostRemove(IoFilterChain, String, NextFilter)}
     *             thrown an exception.
     */
    void clear() throws Exception;

    /**
     * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users
     * don't need to call this method at all. Please use this method only when
     * you implement a new transport or fire a virtual event.
     * 
     * 触发一个IoHandler.sessionCreated(IoSession)事件。
     * 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireSessionCreated(IoSession session);

    /**
     * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users
     * don't need to call this method at all. Please use this method only when
     * you implement a new transport or fire a virtual event.
     * 
     * 触发一个IoHandler.sessionOpened(IoSession)事件。
     * 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireSessionOpened(IoSession session);

    /**
     * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users
     * don't need to call this method at all. Please use this method only when
     * you implement a new transport or fire a virtual event.
     * 
     * 触发一个IoHandler.sessionClosed(IoSession)事件。
     * 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireSessionClosed(IoSession session);

    /**
     * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most
     * users don't need to call this method at all. Please use this method only
     * when you implement a new transport or fire a virtual event.
     * 
     * 触发一个IoHandler.sessionIdle(IoSession, IdleStatus)事件。
     * 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireSessionIdle(IoSession session, IdleStatus status);

    /**
     * Fires a {@link #fireMessageReceived(IoSession, Object)} event. Most users
     * don't need to call this method at all. Please use this method only when
     * you implement a new transport or fire a virtual event.
     * 
     * 触发一个fireMessageReceived(IoSession, Object)事件。
     * 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireMessageReceived(IoSession session, Object message);

    /**
     * Fires a {@link IoHandler#messageSent(IoSession, Object)} event. Most
     * users don't need to call this method at all. Please use this method only
     * when you implement a new transport or fire a virtual event.
     * 
     * 触发一个IoHandler.messageSent(IoSession,Object)事件。
     * 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireMessageSent(IoSession session, WriteRequest request);

    /**
     * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event.
     * Most users don't need to call this method at all. Please use this method
     * only when you implement a new transport or fire a virtual event.
     * 
     * 触发一个IoHandler.exceptionCaught(IoSession, Throwable)事件。
     * 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireExceptionCaught(IoSession session, Throwable cause);

    /**
     * Fires a {@link IoSession#write(Object)} event. Most users don't need to
     * call this method at all. Please use this method only when you implement a
     * new transport or fire a virtual event.
     * 
     * 触发一个IoSession.write(Object)事件。 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireFilterWrite(IoSession session, WriteRequest writeRequest);

    /**
     * Fires a {@link IoSession#close()} event. Most users don't need to call
     * this method at all. Please use this method only when you implement a new
     * transport or fire a virtual event.
     * 
     * 触发一个IoSession.close()事件。 大多数的用户根本不需要调用此方法，除你实现一个新的通讯方式或者解决一个虚拟事件。
     */
    public void fireFilterClose(IoSession session);

    /**
     * Represents a name-filter pair that an {@link IoFilterChain} contains.
     * 封装了name-filter键值对。
     */
    public interface Entry {
        /**
         * Returns the name of the filter.
         */
        String getName();

        /**
         * Returns the filter.
         */
        IoFilter getFilter();

        /**
         * Returns the {@link NextFilter} of the filter.
         */
        NextFilter getNextFilter();
    }
}
